home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1999 March / EnigmA AMIGA RUN 35 (1999)(G.R. Edizioni)(IT)[!][issue 1999-03].iso / earcd / devel / vbcc-68k / vbccm68k.readme
Text File  |  1999-01-01  |  16KB  |  553 lines
  1. Short:    free optimizing ANSI C compiler (68k)
  2. Uploader: volker@vb.franken.de (Volker Barthelmann)
  3. Author:   volker@vb.franken.de (Volker Barthelmann)
  4. Type:     dev/c
  5. Version:  0.7
  6. Replaces: dev/c/vbcc.lha
  7.  
  8. vbcc - portable ANSI C compiler (c) in 1995-99 by Volker Barthelmann
  9.  
  10.  
  11. INTRODUCTION
  12.  
  13.     vbcc is a free portable and retargetable ANSI C compiler.
  14.  
  15.     This archive contains the compiler, preprocessor, assembler, linker,
  16.     frontend, message browser, startup codes, C-libraries, amiga.lib
  17.     replacements as well as several other tools for 68k.
  18.  
  19.     This gives you a complete system that allows to develop programs in
  20.     ANSI C as well as Amiga-specific programs (provided you obtain the
  21.     OS-includes) running on 68k.
  22.  
  23.     All major parts of this distribution (including compiler, preprocessor,
  24.     libraries etc.) have been compiled/assembled with this system and
  25.     apart from the OS-includes everything needed to rebuilt vbcc,
  26.     the libraries and many of the other programs is contained in this
  27.     archive and the corresponding source archive.
  28.  
  29.     Note that the programs in this archive all run on the 68k. There is
  30.     another archive which contains compilers that run on the PPC.
  31.  
  32.  
  33. FEATURES
  34.  
  35.     vbcc..
  36.  
  37.     - comes with source
  38.  
  39.     - is free
  40.  
  41.     - is portable and retargetable
  42.  
  43.     - comes with a global optimizer that can e.g. do global common
  44.       subexpression elimination, constant propagation, function inlining
  45.       and several other optimizations (but is not yet finished and may
  46.       have some bugs)
  47.  
  48.     - should be ANSI compliant
  49.  
  50.     - can generate code that runs on a plain 68000 CPU
  51.  
  52.     - can generate code optimized for 020/030, 040 or 060
  53.  
  54.     - can generate code that uses the 68881/2, 68040/060 FPUs directly
  55.       and comes with appropriate math-libraries
  56.  
  57.     - can generate code that runs on PowerUp-boards
  58.  
  59.     - generates standard Amiga-68k-objects, PPC-ELF-objects or
  60.       WarpOS-EHF-objects
  61.  
  62.     - does not need too much memory
  63.  
  64.     - comes with a message browser
  65.  
  66.     - comes with a config program
  67.  
  68.     - offers a lot of error/warning messages that can be turned on/off
  69.       separately
  70.  
  71.  
  72. WHAT'S NEW
  73.  
  74.     Some changes since the last release:
  75.  
  76.     - bug fixes
  77.  
  78.     - new optimizations
  79.  
  80.     - much improved libaries
  81.  
  82.     - use of Frank Wille's linker vlink
  83.  
  84.     - support for PPC/WarpOS
  85.  
  86.     - support for small data for PPC/ELF and PPC/WarpOS
  87.  
  88.     - support for __saveds (68k, PPC/ELF and PPC/WarpOS)
  89.  
  90.     - support for __far (68k, PPC/EFL and PPC/WarpOS)
  91.  
  92.     - support for __chip (68k and PPC/WarpOS)
  93.  
  94.     - support for auto opening of libraries (68k, PPC/ELF and PPC/WarpOS)
  95.  
  96.     - cleaned up distributions for all three Amiga targets
  97.  
  98.     - checking for unresolved symbols for PPC/ELF
  99.  
  100.     - scheduler for PPC (ELF and WarpOS)
  101.  
  102.  
  103. REQUIREMENTS
  104.  
  105.     To use vbcc you need:
  106.  
  107.     - an Amiga with OS 2.0 or higher
  108.  
  109.     - enough RAM (it is possible to translate small programs with 1MB, but
  110.       for larger programs much more will be needed)
  111.  
  112.     Stuff that is not needed, but may be very useful:
  113.  
  114.     - harddisk
  115.  
  116.     - editor
  117.  
  118.     - make, touch etc.
  119.  
  120.     - the Amiga OS-includes (they can be found on certain CDs)
  121.  
  122.     - pipe-command (to use the message browser)
  123.  
  124.     Also you should know how to use the shell and you should know ANSI C
  125.     (if you need a book I recommend (like everyone) "The C Programming
  126.     Language, Second Edition, ANSI C" by Kernighan and Ritchie).
  127.  
  128.  
  129. LEGAL
  130.  
  131.     Note that this distribution contains several programs, libraries etc.
  132.     that are from different authors and are under different legal status.
  133.     So always read the corresponding doc/guide-file to find out under
  134.     what conditions a certain file may be used, distributed etc.
  135.  
  136.     For the most part you can assume that you may use everything for
  137.     non-commercial purposes and may distribute the unchanged archive
  138.     in whole.
  139.  
  140.     Changing any parts from this archive, distributing parts of it or
  141.     using it commercially might be legal for certain parts, but illegal
  142.     for others, so read all docs carefully before doing any of the above.
  143.  
  144.     This archive contains code written by (this list may be incomplete):
  145.  
  146.     Volker Barthelmann, Frank Wille, Thorsten Schaaps, Dennis Ritchie,
  147.     Matthias Fleischer, Gunther Nikl, Mike Schwartz, Kasper Graversen,
  148.     Johnny Tevessen
  149.  
  150.     However, if you have any comments/problems etc. with anything, please
  151.     do not bother them, but write to me (volker@vb.franken.de) first.
  152.     Exceptions are the parts by Kasper Graversen.
  153.  
  154.  
  155. INSTALLATION/TUTORIAL
  156.  
  157.     [Names of directories, binaries or assigns have changed since earlier
  158.      versions as have config-files. So users of earlier versions should
  159.      read this again and do a complete re-install to avoid problems.]
  160.  
  161.     The first step (which you probably already did) is to extract the
  162.     entire archive (take care to preserve the file attributes). If you
  163.     have several archives of the vbcc distribution you can just extract
  164.     them all to the same place.
  165.  
  166.     The distributed programs are for the most part only usable from a shell.
  167.  
  168.     To use vbcc the following steps are necessary:
  169.  
  170.     1. Go to the subdirectory vbcc/machines/amiga.
  171.  
  172.     2. If you have the Amiga OS-includes copy them into the include
  173.        directory.
  174.  
  175.     3. Execute the script init_vbcc.
  176.  
  177.     4. If you compile larger projects it may be necessary to increase
  178.        the stack further.
  179.  
  180.     If you use vbcc frequently it is probably a good idea to add those
  181.     commands to your user-startup, shell-startup or similar.
  182.  
  183.     Now you should be able to use vbcc. E.g. if you want to compile and
  184.     link the program hello.c you can type
  185.  
  186.         vc hello.c
  187.  
  188.     This will compile and link the file hello.c and create the executable
  189.     a.out in the current directory.
  190.  
  191.         vc hello.c -o hello
  192.  
  193.     will do the same, but the created executable will be called hello.
  194.  
  195.         vc -c t1.c t2.c
  196.  
  197.     will compile t1.c and t2.c without linking, creating the object files
  198.     t1.o and t2.o.
  199.  
  200.         vc t1.o t2.o -o tt
  201.  
  202.     will link them together and create the executable tt.
  203.  
  204.     If your program uses floating point add -lmieee to the commandline
  205.     to link with the math-library, e.g.:
  206.  
  207.         vc calc.c -o calc -lmieee
  208.  
  209.     There is also an extra.lib which includes a few functions that are
  210.     no standard ANSI functions but some people seem to regard them as
  211.     standard functions. If you use one of these add -lextra to the
  212.     commandline and read:
  213.  
  214.         vbcc/machines/amiga/doc/extralibm68k.doc
  215.  
  216.     For further information read the files:
  217.  
  218.         vbcc/doc/vbcc.doc
  219.         vbcc/doc/vc.doc
  220.         vbcc/doc/vbccm68k.doc
  221.         vbcc/machines/amiga/doc/vclibm68k.doc
  222.  
  223.  
  224. SUPPORT FOR OTHER TARGETS
  225.  
  226.     This release of vbcc is able to generate code for 68k, PPC/ELF
  227.     and PPC/WarpOS. If you have installed other backends you can
  228.     choose the target by specifying another config file with the
  229.     '+'-option (e.g. +ppc).
  230.  
  231.     For further details see the corresponding docs for this target.
  232.  
  233.  
  234. CONFIGURATION
  235.  
  236.     The frontend searches for a file vc.config in ENV: and vbcc: to read
  237.     preferences. The provided sample vc.config should be usable and does
  238.     not have to be changed but you can add something to suit your personal
  239.     preferences - read
  240.  
  241.         vbcc/doc/vc.doc
  242.  
  243.     to find out more.
  244.  
  245.  
  246. MESSAGE BROWSER
  247.  
  248.     If you start the message browser with
  249.  
  250.         run vbrowse
  251.  
  252.     it will open a window with a listview gadget. If you have a pipe
  253.     command installed you can now invoke vc via tovbr, e.g.
  254.  
  255.         tovbr vc hello.c
  256.  
  257.     and any output from vc will be displayed in the window of vbrowse
  258.     rather than in the shell. It might be convenient to make an alias like
  259.  
  260.         alias vb tovbr vc
  261.  
  262.     so that invoking vb will automatically display the output in the browser.
  263.  
  264.     If there is an error/warning-message in the browser you can invoke a
  265.     configurable command by double-clicking on the message.
  266.  
  267.     Double-clicking on the quoted line will invoke GoldEd (if you have it
  268.     installed) by default, load the file that caused the error and the cursor
  269.     will be placed on this line in the default configuration. If you use
  270.     another editor or want to change this behaviour have a look at
  271.     vbcc/machines/amiga/doc/vbrowse.doc.
  272.  
  273.     Double-clicking on the error-line (the one below the quoted line) will
  274.     invoke the command showerr that will open the VBCCMessages.guide and
  275.     display a more detailed description of the error (if there is one in
  276.     the guide - there are not yet descriptions for all messages).
  277.  
  278.     Read vbcc/machines/amiga/vbrowse.doc for further information.
  279.  
  280.  
  281. CONTENTS
  282.  
  283.     This archive contains (among others) the following files and directories:
  284.  
  285.     vbcc/
  286.  
  287.             The main directory. The source files for the compiler and the
  288.             builtin preprocessor by Thorsten Schaaps are here.
  289.  
  290.     vbcc/doc/
  291.  
  292.             Host independant documentation for the compiler is in this dir.
  293.  
  294.     vbcc/doc/History
  295.  
  296.             Changes in since earlier versions of the compiler.
  297.  
  298.     vbcc/doc/vbcc.doc
  299.  
  300.             Documentation for the target-independant part of the compiler.
  301.  
  302.     vbcc/doc/vbcc.faq
  303.  
  304.             Frequently asked questions about vbcc.
  305.  
  306.     vbcc/doc/errors.doc
  307.  
  308.             A list of all error/warning-messages from the compiler -
  309.             sometimes with more detailed descriptions.
  310.  
  311.     vbcc/doc/vbccm68k.doc
  312.  
  313.             Documentation for the 68k code generator.
  314.  
  315.     vbcc/doc/vc.doc
  316.  
  317.             Documentation for the compiler-frontend.
  318.  
  319.     vbcc/doc/vlink.doc
  320.  
  321.             Documentation for the linker by Frank Wille.
  322.  
  323.     vbcc/doc/vcpp.doc
  324.  
  325.             Some short comments regarding the preprocessor from the
  326.             lcc-distribution. Read the copyright-notice.
  327.  
  328.     vbcc/doc/building.doc
  329.  
  330.             Documentation on building vbcc.
  331.  
  332.     vbcc/bin/
  333.  
  334.             The directory containing binaries of preprocessor, compiler and
  335.             frontend. Additional binaries may be in machines/xyz/bin/.
  336.  
  337.     vbcc/bin/vbccm68k
  338.  
  339.             The native C compiler for m68k.
  340.  
  341.     vbcc/bin/vbccppc
  342.  
  343.             The C cross-compiler for PPC. Running on m68k.
  344.  
  345.     vbcc/bin/vbccm68k_ppc
  346.  
  347.             The C cross-compiler for m68k. Running on PPC/ELF. (optional)
  348.  
  349.     vbcc/bin/vbccppc_ppc
  350.  
  351.             The native C compiler for PPC/ELF. (optional)
  352.  
  353.     vbcc/bin/vbccm68k_wos
  354.  
  355.             The C cross-compiler for m68k. Running on PPC/WOS. (optional)
  356.  
  357.     vbcc/bin/vbccppc_wos
  358.  
  359.             The native C compiler for PPC/WOS. (optional)
  360.  
  361.     vbcc/bin/vc
  362.  
  363.             The compiler-frontend.
  364.  
  365.     vbcc/bin/vlink
  366.  
  367.             The linker by Frank Wille.
  368.  
  369.     vbcc/bin/vcpp
  370.  
  371.             The preprocessor from the lcc-distribution (by Dennis Ritchie).
  372.  
  373.     vbcc/machines/amiga/doc/
  374.  
  375.             This contains documentation for the Amiga specific parts.
  376.  
  377.     vbcc/machines/amiga/doc/extralibm68k.doc
  378.  
  379.             Documentation for extra.lib.
  380.  
  381.     vbcc/machines/amiga/doc/PhxAss.guide
  382.  
  383.             Documentation for the assembler by Frank Wille.
  384.  
  385.     vbcc/machines/amiga/doc/VBCCMessages.guide
  386.  
  387.             The vbcc/doc/errors.doc in Amigaguide-format (done by Walter
  388.             Doerwald).
  389.  
  390.     vbcc/machines/amiga/doc/vclibm68k.doc
  391.  
  392.             Documentation for the Amiga-C-library.
  393.  
  394.     vbcc/machines/amiga/doc/ixemul.doc
  395.  
  396.             Documentation on using the ixemul.library.
  397.  
  398.     vbcc/machines/amiga/doc/vbrowse.doc
  399.  
  400.             Documentation on the message browser and several connected tools.
  401.  
  402.     vbcc/machines/amiga/doc/fd2lib.doc
  403.  
  404.             Documentation for fd2lib.
  405.  
  406.     vbcc/machines/amiga/doc/minstart.doc
  407.  
  408.             Documentation for minstart.o.
  409.  
  410.     vbcc/machines/amiga/doc/alib.doc
  411.  
  412.             Documentation for alib by Mike Schwartz.
  413.  
  414.     vbcc/machines/amiga/init_vbcc
  415.  
  416.             A sample script to do the necessary assigns etc. to use vbcc.
  417.  
  418.     vbcc/machines/amiga/include
  419.  
  420.             Here you can install the OS-includes.
  421.  
  422.     vbcc/machines/amiga68k/include
  423.  
  424.             This directory contains the standard-ANSI-includes for vc.lib
  425.             on m68k.
  426.  
  427.     vbcc/machines/amiga/bin/
  428.  
  429.             This directory contains all Amiga-specific executables.
  430.  
  431.     vbcc/machines/amiga/bin/PhxAss
  432.  
  433.             The assembler by Frank Wille.
  434.  
  435.     vbcc/machines/amiga/bin/vbrowse
  436.     vbcc/machines/amiga/bin/vsend
  437.     vbcc/machines/amiga/bin/tovbr
  438.     vbcc/machines/amiga/bin/showerr
  439.  
  440.             The message browser and some tools.
  441.  
  442.     vbcc/machines/amiga/bin/fd2lib
  443.  
  444.             fd2lib generates stubs for shared libraries and must be used to
  445.             rebuilt amiga.lib or if you want to use any custom shared-library.
  446.  
  447.     vbcc/machines/amiga/bin/alib
  448.  
  449.             Used to create link-libraries.
  450.  
  451.     vbcc/machines/amiga68k/lib/
  452.  
  453.             This directory contains the link-libraries and startup-codes
  454.             for Amiga68k.
  455.  
  456.     vbcc/machines/amiga68k/lib/startup.o
  457.  
  458.             The standard startup-code for vc.lib.
  459.  
  460.     vbcc/machines/amiga68k/lib/vc.lib
  461.  
  462.             The standard C-library.
  463.  
  464.     vbcc/machines/amiga68k/lib/vcs.lib
  465.  
  466.             The small data C-library.
  467.  
  468.     vbcc/machines/amiga68k/lib/mieee.lib
  469.  
  470.             Math-library that uses the MathIeee-libraries.
  471.  
  472.     vbcc/machines/amiga68k/lib/m881.lib
  473.  
  474.             Math-library that uses FPU-instructions of the 68881/2.
  475.  
  476.     vbcc/machines/amiga68k/lib/m040.lib
  477.  
  478.             Math-library that uses FPU-instructions that do not have to be
  479.             emulated on a 68040 and the Motorola emulation routines
  480.             otherwise.
  481.  
  482.     vbcc/machines/amiga68k/lib/m040o.lib
  483.  
  484.             Math-library that uses FPU-instructions that do not have to be
  485.             emulated on a 68040 and the MathIeee*.library functions
  486.             otherwise.
  487.  
  488.     vbcc/machines/amiga68k/lib/crt0.o
  489.  
  490.             Startup-code for using ixemul.library with large data model.
  491.  
  492.     vbcc/machines/amiga68k/lib/bcrt0.o
  493.  
  494.             Startup-code for using ixemul.library with small data model.
  495.  
  496.     vbcc/machines/amiga68k/lib/ixemul.lib
  497.  
  498.             Stub library for using ixemul.library with large data model.
  499.  
  500.     vbcc/machines/amiga68k/lib/ixemuls.lib
  501.  
  502.             Stub library for using ixemul.library with small data model.
  503.  
  504.     vbcc/machines/amiga68k/lib/amiga.lib
  505.  
  506.             Replacement for the standard amiga.lib.
  507.  
  508.     vbcc/machines/amiga68k/lib/amigas.lib
  509.  
  510.             Small data replacement for the standard amiga.lib.
  511.  
  512.     vbcc/machines/amiga68k/lib/auto.lib
  513.  
  514.             Library for automatic opening of system libraries.
  515.  
  516.     vbcc/machines/amiga68k/lib/autos.lib
  517.  
  518.             Library for automatic opening of system libraries (small data).
  519.  
  520.     vbcc/machines/amiga68k/lib/minstart.o
  521.  
  522.             Small startup-code for small programs that do not use functions
  523.             from the C-library.
  524.  
  525.     vbcc/machines/amiga68k/lib/extra.lib
  526.  
  527.             Very small library containing a few functions some people want.
  528.  
  529.     vbcc/machines/amiga68k/lib/extras.lib
  530.  
  531.             Small data version of the above.
  532.  
  533.  
  534.  
  535. BUGREPORTS/COMMENTS
  536.  
  537.     If you think vbcc generates bad code, throws enforcer hits, crashes,
  538.     seems to be not ANSI-compliant etc. and the problem is not mentioned
  539.     anywhere in this docs as known problem, please send a mail with your
  540.     system configuration, the vbcc version, the command line you used, the
  541.     source that caused the problem and a brief description of the problem to
  542.  
  543.         volker@vb.franken.de
  544.  
  545.     Also if you find problems with the includes, the libraries or you have
  546.     suggestions, dislikes etc. send me a mail.
  547.     Corrections, improvements etc. of the manuals are appreciated, too.
  548.  
  549.  
  550.  
  551. Volker Barthelmann                                      volker@vb.franken.de
  552.  
  553.